home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir31 / tnypl211.zip / README.TXT < prev    next >
Text File  |  1994-06-21  |  14KB  |  358 lines
  1.                     The Psychic Monks present...
  2.  
  3.  ████████████                      ███████▄
  4.  ▀▀▀▀████▀▀▀▀                      ███▌ ▀███
  5.      ████                          ███▌  ███ ████
  6.      ████  ▐██  ███▄██▄  ███  ███  ███▌ ▄███  ▐██    █████▄  ███  ███
  7.      ████       ███▀▀███ ███  ███  ███████▀   ▐██        ██▌ ███  ███
  8.      ████ ████  ███  ███ ███  ███  ███▌       ▐██   ▄██████▌ ███  ███
  9.      ████  ▐██  ███  ███  ▀██████  ███▌       ▐██  ███  ▐██▌  ▀██████
  10.      ████  ▐██  ███  ███      ██▌  ███▌       ▐██  ███  ▐██▌      ██▌
  11.      ████ ▐████ ███  ███  █████▀   ███▌      ▐████  ▀████▀███ █████▀
  12.  
  13.                       Sound Blaster Module Player
  14.                              Version 2.11
  15.  
  16.         The first public digital sound player routines for use with
  17.              Watcom C/C++32 Compiler and DOS/4GW DOS Extender
  18.                      and Borland C++ 3.1 Compiler
  19.  
  20.                     Copyright (c)1994  Carlos Hasan
  21.  
  22.                              (a.k.a. Pel/PM)
  23.  
  24.  
  25.  
  26.  
  27. Introduction
  28. ───────────────────────────────────────────────────────────────────────────────
  29. 1.1     What is Tiny Player?
  30.  
  31.         The Tiny Module Player is a system by which you can play digital
  32. music in your software programs. It was designed for the Watcom C/C++
  33. C compiler and the DOS/4GW Rational Systems DOS Extender. Also, It was
  34. translated to 16-bits to work with Borland C++ 3.1 compiler. It only
  35. supports the Soundblaster(tm) or compatible sound cards.
  36.  
  37.  
  38. 1.2     Hardware requirements
  39.  
  40.         The requirements for this system are a 386 computer and the
  41. Soundblaster(tm) or compatible sound card. It is much better if you have a
  42. fast 386 because you can achive higher mixing rates.
  43.  
  44.  
  45. 1.3     Smileware and contributions
  46.  
  47.         This program has been released as Smileware, which means you can use
  48. this program freely. Anyone can try it out without paying for the software.
  49.         However, if you find this program useful and you want to use it
  50. indefinitely, I will be expecting some contributions. Also, if you are using
  51. this program, do not forget to give me credits in your productions.
  52.         For those which are expecting GUS support in the next release of this
  53. sound player, please send contributions so I can buy a GUS sound card. :)
  54.         For contributions, comments, suggestions, etc use the following
  55. mail addresses to contact the author:
  56.  
  57.         Snail Mail:
  58.                 Carlos Hasan
  59.                 Lo Encalada 144, Depto 22
  60.                 Ñuñoa, Santiago
  61.                 CHILE
  62.  
  63.         Internet E-Mail:
  64.                 chasan@cec.uchile.cl
  65.                 cvaldovi@dcc.uchile.cl
  66.  
  67.  
  68.  
  69. Using the Player
  70. ───────────────────────────────────────────────────────────────────────────────
  71. 2.1     Playing music modules
  72.  
  73.         The player is pretty easy to use. First, you must load any Protracker
  74. or Fastracker music module file using the loading routines. To play the music
  75. module you need the Soundblaster(tm) configuration parameters. To ease things
  76. there is a routine called MODDetect which will automatically detect the card
  77. configuration parameters (I/O port address, IRQ level and DMA channel). This
  78. routine may fail on some systems, so it is always safer to ask the user those
  79. hardware parameters.
  80.         Now, call the routine MODPlayModule to start playing the music file
  81. in the background. The routine parameters are the music module address, the
  82. mixing rate, sound card parameters and polling mode.
  83.         If you do not want to play music in the background, but use the sound
  84. effect channels, you can call this routine passing NULL instead of a valid
  85. music module address.
  86.        The MODStopModule will deinitialize the sound system, and should be
  87. called before exiting your program. This routine will close all the sound
  88. channels (music and sound effect channels).
  89.  
  90.  
  91. 2.2     Playing sound effects
  92.  
  93.         The player supports up to 8 sound channels. The program itself uses
  94. the first channels to play the music module. For example, for a normal
  95. 4 channels module file, the channels 0, 1, 2, and 3 will be used to play
  96. the music module. You can use the others unused channels to play sound
  97. effects and the like.
  98.         The digital sound samples can be loaded from disk using the routine
  99. MODLoadSample which can read standard RIFF/WAV sample files, only 8-bit mono
  100. sound files are supported. After loading the sample, you can play it using
  101. the routine MODPlaySample. There are also routines to change the frequency
  102. and volume of the sound channels.
  103.         You can control the overall volume of the music channels and the
  104. sound effects channels using two routines called MODSetMusicVolume and
  105. MODSetSampleVolume. These routines are very useful to do volume fades of
  106. the music, and for games which are playing sound effects over the music.
  107.  
  108.  
  109. 2.3     Closing Words
  110.  
  111.         First, I'd like to thank Vernor for helping me to write this document,
  112. and to Necros for the wonderful 8 channels module specially maded for this
  113. release. Also, I send greetings to all the others Psychic Monks dudes around.
  114. I should say that the Protracker tune was created from a S3M file, so it does
  115. not sound as good as the original Scream Tracker 3.01 module file.
  116.         I really hope that you find this program useful. It is not the best
  117. or fastest player around, but the multiple sound channels capabilities should
  118. make it very useful to create games, demos, etc.
  119.  
  120.  
  121.  
  122. Reference Guide
  123. ───────────────────────────────────────────────────────────────────────────────
  124.  
  125. 3.1 LISTING OF ROUTINES
  126.  
  127.  MODDetectCard
  128.  ──────────────────────────────────────────────────────────────────────────────
  129.  Function:      Detect Sound Blaster card.
  130.  
  131.  Prototype:     int MODDetectCard(&Port,&IRQ,&DRQ)
  132.  
  133.  Parameters:    Port    - I/O Port address
  134.                 IRQ     - IRQ level
  135.                 DRQ     - DMA channel
  136.  
  137.  Returns:       On success, return a zero value.
  138.                 On error, return a non zero value.
  139.  
  140.  Remarks:       This function will detect the Sound Blaster card and
  141.                 will return the configuration parameters. You cannot
  142.                 call this routine while playing a module.
  143.  
  144.  WARNING:       Actually the routine only detects the I/O Port address
  145.                 and the IRQ level, the DMA channel 1 is always returned
  146.                 by this routine.
  147.  
  148.  
  149.  MODPlayModule
  150.  ──────────────────────────────────────────────────────────────────────────────
  151.  Function:      Start playing a Modulefile.
  152.  
  153.  Prototype:     int MODPlayModule(Song,Chans,Rate,Port,IRQ,DRQ,Mode)
  154.  
  155.  Parameters:    Song    - Address of the Module
  156.                 Chans   - Number of channels (1-8)
  157.                 Rate    - Mixing speed in Hertz (4kHz-22kHz)
  158.                 Port    - I/O Port address (210h..260h)
  159.                 IRQ     - IRQ level (2,3,5,7,10)
  160.                 DRQ     - DMA channel (0,1,3)
  161.                 Mode    - Polling mode (PM_TIMER or PM_MANUAL)
  162.  
  163.  Returns:       On success, return a zero value.
  164.                 On error, return a non zero value.
  165.  
  166.  Remarks:       This function will initialize the Sound Blaster card and
  167.                 will start playing the module file immediately. The module
  168.                 file must be a 4,6 or 8 channels Protracker or FastTracker
  169.                 music module file.
  170.                 The player supports two kinds of channels, music and sample
  171.                 audio channels. The music channels are used by the player
  172.                 to play the module, and the sample channels are used for
  173.                 sound effects and the like.
  174.                 The channels voices 0 to N-1 are used for music channels,
  175.                 where N is the number of channels of the module file.
  176.  
  177.  WARNING:       Using the timer polling mode the system will use the timer
  178.                 interrupt IRQ 0 and will speedup the timer to 70 Hz. The
  179.                 old timer routine is called 18.2 times per second.
  180.  
  181.  
  182.  MODPoll
  183.  ──────────────────────────────────────────────────────────────────────────────
  184.  Function:      Polls the music system in manual mode.
  185.  
  186.  Prototype:     void MODPoll()
  187.  
  188.  Parameters:    None.
  189.  
  190.  Returns:       None.
  191.  
  192.  Remarks:       You MUST call this routine at least 50 times per second when
  193.                 using the manual polling mode while playing a module. There is
  194.                 no need to call it if you are using the timer polling mode.
  195.                 The routine preserves all the 80386 32-bit registers, so
  196.                 there is no need to save the registers if you are calling
  197.                 this routine from your timer interrupt service.
  198.  
  199.  
  200.  MODStopModule
  201.  ──────────────────────────────────────────────────────────────────────────────
  202.  Function:      Stop playing the current Modulefile.
  203.  
  204.  Prototype:     void MODStopModule()
  205.  
  206.  Parameters:    None.
  207.  
  208.  Returns:       None.
  209.  
  210.  Remarks:       This function shuts down the playing system. Must be called
  211.                 before exiting the user program.
  212.  
  213.  
  214.  MODPlaySample
  215.  ──────────────────────────────────────────────────────────────────────────────
  216.  Function:      Play instrument at specified period and volume.
  217.  
  218.  Prototype:     void MODPlaySample(Voice,Instr)
  219.  
  220.  Parameters:    Voice   - Audio channel number (0-7)
  221.                 Instr   - Instrument address
  222.  
  223.  Returns:       None.
  224.  
  225.  Remarks:       This function is useful to play samples over music. The sample
  226.                 structure holds the period, volume and the address of the 8-bit
  227.                 signed samples to be played in the channel.
  228.                 The amiga period value can be translated to hertz using the
  229.                 following formula:  Hertz = 8363*428/Period
  230.  
  231.  
  232.  MODStopSample
  233.  ──────────────────────────────────────────────────────────────────────────────
  234.  Function:      Stop a sample channel.
  235.  
  236.  Prototype:     void MODStopSample(Voice)
  237.  
  238.  Parameters:    Voice   - Audio channel number (0-7)
  239.  
  240.  Remarks:       This function will stop the specified voice setting the channel
  241.                 volume to zero. The voice should be a sample channel.
  242.  
  243.  
  244.  MODSetPeriod
  245.  ──────────────────────────────────────────────────────────────────────────────
  246.  Function:      Set the sample channel period value.
  247.  
  248.  Prototype:     void MODSetPeriod(Voice,Period)
  249.  
  250.  Parameters:    Voice   - Audio channel number (0-7)
  251.                 Period  - Amiga Period (113-856)
  252.  
  253.  Returns:       None.
  254.  
  255.  Remarks:       This function will change the current frequency of the sample
  256.                 channel. The voice should be a sample channel.
  257.  
  258.  
  259.  MODSetVolume
  260.  ──────────────────────────────────────────────────────────────────────────────
  261.  Function:      Set the sample channel volume.
  262.  
  263.  Prototype:     void MODSetVolume(Voice,Volume)
  264.  
  265.  Parameters:    Voice   - Audio channel number (0-7)
  266.                 Volume  - Volume (0-64)
  267.  
  268.  Returns:       None.
  269.  
  270.  Remarks:       This function will change the channel volume. The voice should
  271.                 be a sample channel.
  272.  
  273.  
  274.  MODSetMusicVolume
  275.  ──────────────────────────────────────────────────────────────────────────────
  276.  Function:      Set the global music channels volume.
  277.  
  278.  Prototype:     void MODSetMusicVolume(Volume)
  279.  
  280.  Parameters:    Volume  - Volume (0-255)
  281.  
  282.  Returns:       None.
  283.  
  284.  Remarks:       This function will set the global volume for all the music
  285.                 channels.
  286.  
  287.  
  288.  MODSetSampleVolume
  289.  ──────────────────────────────────────────────────────────────────────────────
  290.  Function:      Set the global sample channels volume.
  291.  
  292.  Prototype:     void MODSetSampleVolume(Volume)
  293.  
  294.  Parameters:    Volume  - Volume (0-255)
  295.  
  296.  Returns:       None.
  297.  
  298.  Remarks:       This function will set the global volume for all the sample
  299.                 channels.
  300.  
  301.  
  302.  MODLoadModule
  303.  ──────────────────────────────────────────────────────────────────────────────
  304.  Function:      Load Module file from disk.
  305.  
  306.  Prototype:     Module *MODLoadModule(Path)
  307.  
  308.  Parameters:    Path    - Module file name.
  309.  
  310.  Returns:       The module structure address or NULL of error.
  311.  
  312.  Remarks:       This function loads a 4,6 or 8 channels standard Protracker
  313.                 or Fastracker module music file from disk.
  314.  
  315.  
  316.  MODFreeModule
  317.  ──────────────────────────────────────────────────────────────────────────────
  318.  Function:      Free Module file from memory.
  319.  
  320.  Prototype:     void MODFreeModule(Song)
  321.  
  322.  Parameters:    Song    - Module file address.
  323.  
  324.  Returns:       None.
  325.  
  326.  Remarks:       This function frees the module music from memory. You cannot
  327.                 free a module while it is being played.
  328.  
  329.  
  330.  MODLoadSample
  331.  ──────────────────────────────────────────────────────────────────────────────
  332.  Function:      Load sample file from disk.
  333.  
  334.  Prototype:     Sample *MODLoadSample(Path)
  335.  
  336.  Parameters:    Path    - WAV file name.
  337.  
  338.  Returns:       The sample structure address or NULL of error.
  339.  
  340.  Remarks:       This function loads a RIFF/WAV sample file, the player only
  341.                 supports 8-bit mono unsigned sample file formats.
  342.  
  343.  
  344.  MODFreeSample
  345.  ──────────────────────────────────────────────────────────────────────────────
  346.  Function:      Free Sample file from memory.
  347.  
  348.  Prototype:     void MODFreeSample(Instr)
  349.  
  350.  Parameters:    Instr   - Sample file address.
  351.  
  352.  Returns:       None.
  353.  
  354.  Remarks:       This function frees the sample file from memory. You cannot
  355.                 free a sample while it is being played.
  356.  
  357.  
  358.